<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

<!-- Mirrored from www.wolfssl.com/wolfSSL/Docs-wolfssl-manual-10-wolfcrypt-usage-reference.html by HTTrack Website Copier/3.x [XR&CO'2014], Tue, 17 Jan 2017 13:29:11 GMT -->
<!-- Added by HTTrack --><meta http-equiv="content-type" content="text/html;charset=UTF-8" /><!-- /Added by HTTrack -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<meta name="Generator" content="iWeb 3.0.4"/>
<meta name="iWeb-Build" content="local-build-20170103"/>
<meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7"/>
<meta name="viewport" content="width=770"/>
<title>wolfSSL - Docs | wolfSSL Manual - Chapter 10 (wolfCrypt Usage Reference)</title>
<link rel="stylesheet" type="text/css" media="screen,print" href="Docs-wolfssl-manual-10-wolfcrypt-usage-reference_files/Docs-wolfssl-manual-10-wolfcrypt-usage-reference.css"/>
<!--[if lt IE 8]><link rel='stylesheet' type='text/css' media='screen,print' href='Docs-wolfssl-manual-10-wolfcrypt-usage-reference_files/Docs-wolfssl-manual-10-wolfcrypt-usage-referenceIE.css'/><![endif]-->
<!--[if gte IE 8]><link rel='stylesheet' type='text/css' media='screen,print' href='Media/IE8.css'/><![endif]-->
<script type="text/javascript" src="Scripts/iWebSite.js"></script>
<script type="text/javascript" src="Docs-wolfssl-manual-10-wolfcrypt-usage-reference_files/Docs-wolfssl-manual-10-wolfcrypt-usage-reference.js"></script>
<meta name="description" content="A usage reference for wolfCrypt, the cryptography library used by the wolfSSL embedded SSL library (formerly CyaSSL)."/><meta name="keywords" content="mbedded ssl, ssl library, tls library, embedded crypto, cryptology, crypto tutorial, md4, md5, sha, ripemd, hmac, aes, des, 3des, rabbit, arc4, hc-128, rsa, dsa, dh, edh, tls 1.2, small openssl, smart grid, connected home, ecc, lightweight ssl, suite b, encryption security software, ssl inspection"/><meta name="robots" content="follow,index"/> <script>(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)})(window,document,'script','../../www.google-analytics.com/analytics.js','ga');ga('create','UA-64826966-1','auto');ga('send','pageview');</script>
 
<script>//<![CDATA[
window.zEmbed||function(e,t){var n,o,d,i,s,a=[],r=document.createElement("iframe");window.zEmbed=function(){a.push(arguments)},window.zE=window.zE||window.zEmbed,r.src="javascript:false",r.title="",r.role="presentation",(r.frameElement||r).style.cssText="display: none",d=document.getElementsByTagName("script"),d=d[d.length-1],d.parentNode.insertBefore(r,d),i=r.contentWindow,s=i.document;try{o=s}catch(c){n=document.domain,r.src='javascript:var d=document.open();d.domain="'+n+'";void(0);',o=s}o.open()._l=function(){var o=this.createElement("script");n&&(this.domain=n),o.id="js-iframe-async",o.src=e,this.t=+new Date,this.zendeskHost=t,this.zEQueue=a,this.body.appendChild(o)},o.write('<body onload="document._l();">'),o.close()}("../../assets.zendesk.com/embeddable_framework/main.js","wolfssl.zendesk.com");
//]]></script>
  </head>
<body style="background: rgb(255, 255, 255); margin: 0pt; " onload="onPageLoad();">
<div style="text-align: center; ">
<div style="margin-bottom: 20px; margin-left: auto; margin-right: auto; margin-top: 20px; overflow: hidden; position: relative; word-wrap: break-word;  background: rgb(255, 255, 255); text-align: left; width: 770px; " id="body_content">
<div style="float: left; margin-left: 0px; position: relative; width: 770px; z-index: 0; " id="nav_layer">
<div style="height: 0px; line-height: 0px; " class="bumper"> </div>
<div style="clear: both; height: 0px; line-height: 0px; " class="spacer"> </div>
</div>
<div style="float: left; height: 0px; line-height: 0px; margin-left: 0px; position: relative; width: 770px; z-index: 10; " id="header_layer">
<div style="height: 0px; line-height: 0px; " class="bumper"> </div>
</div>
<div style="margin-left: 0px; position: relative; width: 770px; z-index: 5; " id="body_layer">
<div style="height: 0px; line-height: 0px; " class="bumper"> </div>
<div id="id1" style="height: 38px; left: 375px; position: absolute; top: 157px; width: 361px; z-index: 1; " class="style_SkipStroke shape-with-text">
<div class="text-content graphic_textbox_layout_style_default_External_361_38" style="padding: 0px; ">
<div class="graphic_textbox_layout_style_default">
<p style="padding-bottom: 0pt; padding-top: 0pt; " class="paragraph_style">wolfSSL Manual</p>
</div>
</div>
</div>
<div id="id2" style="height: 8399px; left: 35px; position: absolute; top: 281px; width: 701px; z-index: 1; " class="style_SkipStroke shape-with-text">
<div class="text-content graphic_textbox_layout_style_default_External_701_8399" style="padding: 0px; ">
<div class="graphic_textbox_layout_style_default">
<p style="padding-top: 0pt; " class="paragraph_style_1">Chapter 10: wolfCrypt (formerly CTaoCrypt) Usage Reference<span class="style"><br/></span></p>
<p class="paragraph_style_2"><br/></p>
<p class="paragraph_style_3"><br/></p>
<p class="paragraph_style_4">wolfCrypt is the cryptography library primarily used by wolfSSL. It is optimized for speed, small footprint, and portability. wolfSSL interchange with other cryptography libraries as required.<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">Types used in the examples:<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_5">typedef unsigned char byte;<br/></p>
<p class="paragraph_style_5">typedef unsigned int  word32;<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_3">10.1 Hash Functions<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_6">10.1.1 MD4<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><span class="style_1">NOTE:</span>  MD4 is outdated and considered broken. Please consider using a different hashing function if possible. <br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">To use MD4 include the MD4 header &quot;<span class="style_2">wolfssl/ctaocrypt/md4.h</span>&quot;. The structure to use is <span class="style_3">Md4</span>, which is a typedef. Before using, the hash initialization must be done with the <span class="style_3">InitMd4</span>() call. Use <span class="style_3">Md4Update</span>() to update the hash and <span class="style_3">Md4Final</span>() to retrieve the final hash<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><span class="style_4">byte md4sum[MD4_DIGEST_SIZE];<br/></span></p>
<p class="paragraph_style_4"><span class="style_4">byte buffer[1024];      <br/></span></p>
<p class="paragraph_style_4"><span class="style_4">// fill buffer with data to hash<br/></span></p>
<p class="paragraph_style_4"><span class="style_4"><br/></span></p>
<p class="paragraph_style_4"><span class="style_4">Md4 md4;<br/></span></p>
<p class="paragraph_style_4"><span class="style_4">InitMd4(&amp;md4);<br/></span></p>
<p class="paragraph_style_4"><span class="style_4"><br/></span></p>
<p class="paragraph_style_4"><span class="style_4">Md4Update(&amp;md4, buffer, sizeof(buffer));  // can be called again and again<br/></span></p>
<p class="paragraph_style_4"><span class="style_4">Md4Final(&amp;md4, md4sum);  </span>       <br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><span class="style_3">md4sum</span> now contains the digest of the hashed data in <span class="style_3">buffer</span>.<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_6">10.1.2 MD5 <br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">To use MD5 include the MD5 header &quot;<span class="style_2">wolfssl/ctaocrypt/md5.h</span>&quot;. The structure to use is <span class="style_3">Md5</span>, which is a typedef. Before using, the hash initialization must be done with the <span class="style_3">InitMd5</span>() call. Use <span class="style_3">Md5Update</span>() to update the hash and <span class="style_3">Md5Final</span>() to retrieve the final hash<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><span class="style_4">byte md5sum[MD5_DIGEST_SIZE];<br/></span></p>
<p class="paragraph_style_4"><span class="style_4">byte buffer[1024];      <br/></span></p>
<p class="paragraph_style_4"><span class="style_4">// fill buffer with data to hash<br/></span></p>
<p class="paragraph_style_4"><span class="style_4"><br/></span></p>
<p class="paragraph_style_4"><span class="style_4">Md5 md5;<br/></span></p>
<p class="paragraph_style_4"><span class="style_4">InitMd5(&amp;md5);<br/></span></p>
<p class="paragraph_style_4"><span class="style_4"><br/></span></p>
<p class="paragraph_style_4"><span class="style_4">Md5Update(&amp;md5, buffer, sizeof(buffer));  // can be called again and again<br/></span></p>
<p class="paragraph_style_4"><span class="style_4">Md5Final(&amp;md5, md5sum);     </span>    <br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><span class="style_3">md5sum</span> now contains the digest of the hashed data in <span class="style_3">buffer</span>.<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_6">10.1.3 SHA / SHA-224 / SHA-256 / SHA-384 / SHA-512<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4">To use SHA include the SHA header &quot;<span class="style_2">wolfssl/ctaocrypt/sha.h</span>&quot;. The structure to use is <span class="style_3">Sha</span>, which is a typedef. Before using, the hash initialization must be done with the <span class="style_3">InitSha</span>() call. Use <span class="style_3">ShaUpdate</span>() to update the hash and <span class="style_3">ShaFinal</span>() to retrieve the final hash:<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_5">byte shaSum[SHA_DIGEST_SIZE];<br/></p>
<p class="paragraph_style_5">byte buffer[1024];      <br/></p>
<p class="paragraph_style_5">// fill buffer with data to hash<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">Sha sha;<br/></p>
<p class="paragraph_style_5">InitSha(&amp;sha);<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">ShaUpdate(&amp;sha, buffer, sizeof(buffer));  // can be called again and again<br/></p>
<p class="paragraph_style_5">ShaFinal(&amp;sha, shaSum);<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4"><span class="style_3">shaSum</span> now contains the digest of the hashed data in <span class="style_3">buffer</span>.<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">To use either SHA-256 or SHA-512, follow the same steps as shown above, but use either the “<span class="style_2">wolfssl/ctaocrypt/sha256.h</span>” or “<span class="style_2">wolfssl/ctaocrypt/sha512.h</span>”.  The SHA-256 and SHA-512 functions are named similarly to the SHA functions.  <br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">For <span class="style_3">SHA-256</span>, the functions InitSha256(), Sha256Update(), and Sha256Final() will be used with the structure Sha256.<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">For <span class="style_3">SHA-512</span>, the functions InitSha512(), Sha512Update(), and Sha512Final() will be used with the structure Sha512.<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_6">10.1.4 BLAKE2b<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">To use BLAKE2b (a SHA-3 finalist) include the BLAKE2b header &quot;<span class="style_3">wolfssl/wolfcrypt/blake2.h</span>&quot;. The structure to use is <span class="style_3">Blake2b</span>, which is a typedef. Before using, the hash initialization must be done with the <span class="style_3">wc_InitBlake2b</span>() call. Use <span class="style_3">wc_Blake2bUpdate</span>() to update the hash and <span class="style_3">wc_Blake2bFinal</span>() to retrieve the final hash:<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_5">byte digest[64];<br/></p>
<p class="paragraph_style_5">byte input[64];/*fill input with data to hash*/<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">Blake2b b2b;<br/></p>
<p class="paragraph_style_5">wc_InitBlake2b(&amp;b2b, 64);<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">wc_Blake2bUpdate(&amp;b2b, input, sizeof(input));<br/></p>
<p class="paragraph_style_5">wc_Blake2bFinal(&amp;b2b, digest, 64);<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_4">The second parameter to wc_InitBlake2b() should be the final digest size.  digest now contains the digest of the hashed data in buffer.<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">Example usage can be found in the wolfCrypt test application (wolfcrypt/test/test.c), inside the blake2b_test() function.<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_6">10.1.5 RIPEMD-160<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">To use RIPEMD-160, include the header &quot;<span class="style_2">wolfssl/ctaocrypt/ripemd.h</span>&quot;. The structure to use is <span class="style_3">RipeMd</span>, which is a typedef. Before using, the hash initialization must be done with the <span class="style_3">InitRipeMd</span>() call. Use <span class="style_3">RipeMdUpdate</span>() to update the hash and <span class="style_3">RipeMdFinal</span>() to retrieve the final hash<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><span class="style_4">byte ripeMdSum[RIPEMD_DIGEST_SIZE];<br/></span></p>
<p class="paragraph_style_4"><span class="style_4">byte buffer[1024];      <br/></span></p>
<p class="paragraph_style_4"><span class="style_4">// fill buffer with data to hash<br/></span></p>
<p class="paragraph_style_4"><span class="style_4"><br/></span></p>
<p class="paragraph_style_4"><span class="style_4">RipeMd ripemd;<br/></span></p>
<p class="paragraph_style_4"><span class="style_4">InitRipeMd(&amp;ripemd);<br/></span></p>
<p class="paragraph_style_4"><span class="style_4"><br/></span></p>
<p class="paragraph_style_4"><span class="style_4">RipeMdUpdate(&amp;ripemd, buffer, sizeof(buffer));  // can be called again and again<br/></span></p>
<p class="paragraph_style_4"><span class="style_4">RipeMdFinal(&amp;ripemd, ripeMdSum);      </span>   <br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><span class="style_3">ripeMdSum</span> now contains the digest of the hashed data in <span class="style_3">buffer</span>.<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_3">10.2 Keyed Hash Functions<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_6">10.2.1 HMAC<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">wolfCrypt currently provides HMAC for message digest needs. The structure <span class="style_3">Hmac</span> is found in the header &quot;<span class="style_2">wolfssl/ctaocrypt/hmac.h</span>&quot;. HMAC initialization is done with <span class="style_3">HmacSetKey</span>().  3 different types are supported with HMAC; MD5, SHA, and SHA-256. Here's an example with SHA-256.<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_5">Hmac    hmac;<br/></p>
<p class="paragraph_style_5">bytekey[24];    // fill key with keying material<br/></p>
<p class="paragraph_style_5">bytebuferr[2048];   // fill buffer with data to digest<br/></p>
<p class="paragraph_style_5">bytehmacDigest[SHA256_DIGEST_SIZE];<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">HmacSetKey(&amp;hmac, SHA256, key, sizeof(key));<br/></p>
<p class="paragraph_style_5">HmacUpdate(&amp;hmac, buffer, sizeof(buffer));<br/></p>
<p class="paragraph_style_5">HmacFinal(&amp;hmac, hmacDigest);<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4"><span class="style_3">hmacDigest</span> now contains the digest of the hashed data in <span class="style_3">buffer</span>.<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_6">10.2.2 GMAC<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">wolfCrypt also provides GMAC for message digest needs. The structure Gmac is found in the header &quot;<span class="style_5">wolfssl/ctaocrypt/aes.h</span>&quot;, as it is an application AES-GCM. GMAC initialization is done with <span class="style_3">GmacSetKey()</span>.<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_5">Gmac    gmac;<br/></p>
<p class="paragraph_style_5">bytekey[16];    // fill key with keying material<br/></p>
<p class="paragraph_style_5">byte iv[12];// fill iv with an initialization vector<br/></p>
<p class="paragraph_style_5">bytebuffer[2048];   // fill buffer with data to digest<br/></p>
<p class="paragraph_style_5">bytegmacDigest[16];<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">GmacSetKey(&amp;gmac, key, sizeof(key));<br/></p>
<p class="paragraph_style_5">GmacUpdate(&amp;hmac, iv, sizeof(iv), buffer, sizeof(buffer),<br/></p>
<p class="paragraph_style_5">    gmacDigest, sizeof(gmacDigest));<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4"><span class="style_3">gmacDigest </span>now contains the digest of the hashed data in <span class="style_3">buffer</span>.<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_7">10.2.3 Poly1305<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">wolfCrypt also provides Poly1305 for message digest needs. The structure Poly1305 is found in the header &quot;<span class="style_3">wolfssl/wolfcrypt/poly1305.h</span>&quot;. Poly1305 initialization is done with <span class="style_3">Poly1305SetKey</span>(). The process of setting a key in Poly1305 should be done again, with a new key, when next using Poly1305 after <span class="style_3">Poly1305Final</span>() has been called. <br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_5">Poly1305    pmac;<br/></p>
<p class="paragraph_style_5">bytekey[32];    // fill key with keying material<br/></p>
<p class="paragraph_style_5">bytebuffer[2048];   // fill buffer with data to digest<br/></p>
<p class="paragraph_style_5">bytepmacDigest[16];<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">Poly1305SetKey(&amp;pmac, key, sizeof(key));<br/></p>
<p class="paragraph_style_5">Poly1305Update(&amp;pmac, buffer, sizeof(buffer));<br/></p>
<p class="paragraph_style_5">Poly1305Final(&amp;pmac, pmacDigest);<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><span class="style_3">pmacDigest</span> now contains the digest of the hashed data in <span class="style_3">buffer</span>.<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_3">10.3 Block Ciphers<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_6">10.3.1 AES<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4">wolfCrypt provides support for AES with key sizes of 16 bytes (128 bits), 24 bytes (192 bits), or 32 bytes (256 bits). Supported AES modes include CBC, CTR, GCM, and CCM-8.  <br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">CBC mode is supported for both encryption and decryption and is provided through the <span class="style_3">wc_AesSetKey</span>(), <span class="style_3">wc_AesCbcEncrypt</span>() and <span class="style_3">wc_AesCbcDecrypt</span>() functions. Please include the header &quot;<span class="style_3">wolfssl/wolfcrypt/aes.h</span>&quot;  to use AES. AES has a block size of 16 bytes and the IV should also be 16 bytes. Function usage is usually as follows:<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_5">Aes enc;<br/></p>
<p class="paragraph_style_5">Aes dec;<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">const byte key[] = {  // some 24 byte key };<br/></p>
<p class="paragraph_style_5">const byte iv[] = { // some 16 byte iv };<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">byte plain[32];   // an increment of 16, fill with data<br/></p>
<p class="paragraph_style_5">byte cipher[32];<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">// encrypt<br/></p>
<p class="paragraph_style_5">AesSetKey(&amp;enc, key, sizeof(key), iv, AES_ENCRYPTION);<br/></p>
<p class="paragraph_style_5">AesCbcEncrypt(&amp;enc, cipher, plain, sizeof(plain));<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4"><span class="style_3">cipher</span> now contains the cipher text from the plain text.<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_5">// decrypt<br/></p>
<p class="paragraph_style_5">AesSetKey(&amp;dec, key, sizeof(key), iv, AES_DECRYPTION);<br/></p>
<p class="paragraph_style_5">AesCbcDecrypt(&amp;dec, plain, cipher, sizeof(cipher));<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4"><span class="style_3">plain</span> now contains the original plaintext from the cipher text.<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">wolfCrypt also supports CTR (Counter), GCM (Galois/Counter), and CCM-8 (Counter with CBC-MAC) modes of operation for AES.  When using these modes, like CBC, include the “<span class="style_3">wolfssl/wolfcrypt/aes.h</span>” header.<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">CTR mode is available for encryption through the <span class="style_3">wc_AesCtrEncrypt</span>() function.  <br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">GCM mode is available for both encryption and decryption through the <span class="style_3">wc_AesGcmSetKey</span>(), <span class="style_3">wc_AesGcmEncrypt</span>(), and <span class="style_3">wc_AesGcmDecrypt</span>() functions.  For a usage example, see the aesgcm_test() function in &lt;wolfssl_root&gt;/wolfcrypt/test/test.c.<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">CCM-8 mode is supported for both encryption and decryption through the <span class="style_3">wc_AesCcmSetKey</span>(), <span class="style_3">wc_AesCcmEncrypt</span>(), and <span class="style_3">wc_AesCcmDecrypt</span>() functions.  For a usage example, see the aesccm_test() function in &lt;wolfssl_root&gt;/wolfcrypt/test/test.c.<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_6">10.3.2 DES and 3DES<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4">wolfCrypt provides support for DES and 3DES (Des3 since 3 is an invalid leading C identifier). To use these include the header &quot;<span class="style_2">wolfssl/ctaocrypt/des.h</span>&quot;. The structures you can use are <span class="style_3">Des</span> and <span class="style_3">Des3</span>. Initialization is done through <span class="style_3">Des_SetKey</span>() or <span class="style_3">Des3_SetKey</span>(). CBC encryption/decryption is provided through <span class="style_3">Des_CbcEnrypt</span>() / <span class="style_3">Des_CbcDecrypt</span>() and <span class="style_3">Des3_CbcEncrypt</span>() / <span class="style_3">Des3_CbcDecrypt</span>(). Des has a key size of 8 bytes (24 for 3DES) and the block size is 8 bytes, so only pass increments of 8 bytes to encrypt/decrypt functions. If your data isn't in a block size increment you'll need to add padding to make sure it is. Each <span class="style_3">SetKey</span>() also takes an IV (an initialization vector that is the same size as the key size). Usage is usually like the following:<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_5">Des3 enc;<br/></p>
<p class="paragraph_style_5">Des3 dec;<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">const byte key[] = {  // some 24 byte key };<br/></p>
<p class="paragraph_style_5">const byte iv[] = { // some 24 byte iv };<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">byte plain[24];   // an increment of 8, fill with data<br/></p>
<p class="paragraph_style_5">byte cipher[24];<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">// encrypt<br/></p>
<p class="paragraph_style_5">Des3_SetKey(&amp;enc, key, iv, DES_ENCRYPTION);<br/></p>
<p class="paragraph_style_5">Des3_CbcEncrypt(&amp;enc, cipher, plain, sizeof(plain));<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><span class="style_3">cipher</span> now contains the cipher text from the plain text.<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_5">// decrypt<br/></p>
<p class="paragraph_style_5">Des3_SetKey(&amp;dec, key, iv, DES_DECRYPTION);<br/></p>
<p class="paragraph_style_5">Des3_CbcDecrypt(&amp;dec, plain, cipher, sizeof(cipher));<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4"><span class="style_3">plain</span> now contains the original plaintext from the cipher text.<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_6">10.3.3 Camellia<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4">wolfCrypt provides support for the Camellia block cipher. To use Camellia include the header &quot;<span class="style_3">wolfssl/wolfcrypt/camellia.h</span>&quot;. The structure you can use is called Camellia. Initialization is done through <span class="style_3">CamelliaSetKey</span>(). CBC encryption/decryption is provided through <span class="style_3">CamelliaCbcEnrypt</span>() and <span class="style_3">CamelliaCbcDecrypt</span>() while direct encryption/decryption is provided through CamelliaEncryptDirect() and CamelliaDecryptDirect().<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">For usage examples please see the camellia_test() function in &lt;wolfssl_root&gt;/wolfcrypt/test/test.c.<br/></p>
<p class="paragraph_style_4">  <br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_3">10.4 Stream Ciphers<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_6">10.4.1 ARC4<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4">The most common stream cipher used on the Internet is ARC4. wolfCrypt supports it through the header &quot;<span class="style_2">wolfssl/ctaocrypt/arc4.h</span>&quot;.  Usage is simpler than block ciphers because there is no block size and the key length can be any length. The following is a typical usage of ARC4.<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_5">Arc4 enc;<br/></p>
<p class="paragraph_style_5">Arc4 dec;<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">const byte key[] = {  // some key any length};<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">byte plain[27];   // no size restriction, fill with data<br/></p>
<p class="paragraph_style_5">byte cipher[27];<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">// encrypt<br/></p>
<p class="paragraph_style_5">Arc4SetKey(&amp;enc, key, sizeof(key));<br/></p>
<p class="paragraph_style_5">Arc4Process(&amp;enc, cipher, plain, sizeof(plain));<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><span class="style_3">cipher</span> now contains the cipher text from the plain text.<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_5">// decrypt<br/></p>
<p class="paragraph_style_5">Arc4SetKey(&amp;dec, key, sizeof(key));<br/></p>
<p class="paragraph_style_5">Arc4Process(&amp;dec, plain, cipher, sizeof(cipher));<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><span class="style_3">plain</span> now contains the original plaintext from the cipher text.<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_6">10.4.2 RABBIT<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4">A newer stream cipher gaining popularity is RABBIT. This stream cipher can be used through wolfCrypt by including the header &quot;<span class="style_2">wolfssl/ctaocrypt/rabbit.h</span>&quot;. RABBIT is very fast compared to ARC4, but has key constraints of 16 bytes (128 bits) and an optional IV of 8 bytes (64 bits). Otherwise usage is exactly like ARC4:<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_5">Rabbit enc;<br/></p>
<p class="paragraph_style_5">Rabbit dec;<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">const byte key[] = {  // some key 16 bytes};<br/></p>
<p class="paragraph_style_5">const byte iv[] = { // some iv 8 bytes };<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">byte plain[27];   // no size restriction, fill with data<br/></p>
<p class="paragraph_style_5">byte cipher[27];<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">// encrypt<br/></p>
<p class="paragraph_style_5">RabbitSetKey(&amp;enc, key, iv);  // iv can be a NULL pointer<br/></p>
<p class="paragraph_style_5">RabbitProcess(&amp;enc, cipher, plain, sizeof(plain));<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><span class="style_3">cipher</span> now contains the cipher text from the plain text.<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_5">// decrypt<br/></p>
<p class="paragraph_style_5">RabbitSetKey(&amp;dec, key, iv);<br/></p>
<p class="paragraph_style_5">RabbitProcess(&amp;dec, plain, cipher, sizeof(cipher));<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><span class="style_3">plain</span> now contains the original plaintext from the cipher text.<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_6">10.4.3 HC-128<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4">Another stream cipher in current use is HC-128, which is even faster than RABBIT (about 5 times faster than ARC4).  To use it with wolfCrypt, please include the header &quot;<span class="style_2">wolfssl/ctaocrypt/hc128.h</span>&quot;. HC-128 also uses 16 bytes keys (128 bits) but uses 16 bytes vs (128 bits) unlike RABBIT.<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_5">HC128 enc;<br/></p>
<p class="paragraph_style_5">HC128 dec;<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">const byte key[] = {  // some key 16 bytes};<br/></p>
<p class="paragraph_style_5">const byte iv[] = { // some iv 16 bytes };<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">byte plain[37];   // no size restriction, fill with data<br/></p>
<p class="paragraph_style_5">byte cipher[37];<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">// encrypt<br/></p>
<p class="paragraph_style_5">Hc128_SetKey(&amp;enc, key, iv);  // iv can be a NULL pointer<br/></p>
<p class="paragraph_style_5">Hc128_Process(&amp;enc, cipher, plain, sizeof(plain));<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><span class="style_3">cipher</span> now contains the cipher text from the plain text.<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_5">// decrypt<br/></p>
<p class="paragraph_style_5">Hc128_SetKey(&amp;dec, key, iv);<br/></p>
<p class="paragraph_style_5">Hc128_Process(&amp;dec, plain, cipher, sizeof(cipher));<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4"><span class="style_3">plain</span> now contains the original plaintext from the cipher text.<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_6">10.4.4 ChaCha<br/></p>
<p class="paragraph_style_6"> <br/></p>
<p class="paragraph_style_4">ChaCha with 20 rounds is slightly faster than ARC4 while maintaining a high level of security.  To use it with wolfCrypt, please include the header &quot;wolfssl/wolfcrypt/chacha.h&quot;. ChaCha typically uses 32 byte keys (256 bit) but can also use 16 byte keys (128 bits).<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_5">CHACHA enc;<br/></p>
<p class="paragraph_style_5">CHACHA dec;<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">const byte key[] = {  // some key 32 bytes};<br/></p>
<p class="paragraph_style_5">const byte iv[]  = {  // some iv 12 bytes };<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">byte plain[37];   // no size restriction, fill with data<br/></p>
<p class="paragraph_style_5">byte cipher[37];<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">// encrypt<br/></p>
<p class="paragraph_style_5">Chacha_SetKey(&amp;enc, key, keySz);<br/></p>
<p class="paragraph_style_5">Chacha_SetIV(&amp;enc, iv, counter); //counter is the start block <br/></p>
<p class="paragraph_style_5"> //counter is usually set as 0<br/></p>
<p class="paragraph_style_5">Chacha_Process(&amp;enc, cipher, plain, sizeof(plain));<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">cipher now contains the cipher text from the plain text.<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_5">// decrypt<br/></p>
<p class="paragraph_style_5">Chacha_SetKey(&amp;enc, key, keySz);<br/></p>
<p class="paragraph_style_5">Chacha_SetIV(&amp;enc, iv, counter);<br/></p>
<p class="paragraph_style_5">Chacha_Process(&amp;enc, plain, cipher, sizeof(cipher));<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">plain now contains the original plaintext from the cipher text.<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">Chacha_SetKey only needs to be set once but for each packet of information sent Chacha_SetIV must be called with a new iv (nonce). Counter is set as an argument to allow for partially decrypting/encrypting information by starting at a different block when performing the encrypt/decrypt process, but in most cases is set to 0. <span class="style_3">ChaCha should not be used without a mac algorithm ie Poly1305 , hmac.<br/></span></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_3">10.5 Public Key Cryptography<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_6">10.5.1 RSA<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4">wolfCrypt provides support for RSA through the header &quot;<span class="style_2">wolfssl/ctaocrypt/rsa.h</span>&quot;. There are two types of RSA keys, public and private. A public key allows anyone to encrypt something that only the holder of the private key can decrypt. It also allows the private key holder to sign something and anyone with a public key can verify that only the private key holder actually signed it. Usage is usually like the following:<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_5">RsaKey rsaPublicKey;<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">byte publicKeyBuffer[]  = { // holds the raw data from the key, maybe from a file <br/></p>
<p class="paragraph_style_5">                               like RsaPublicKey.der };<br/></p>
<p class="paragraph_style_5">word32 idx = 0;             //  where to start reading into the buffer<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">RsaPublicKeyDecode(publicKeyBuffer, &amp;idx, &amp;rsaPublicKey, sizeof(publicKeyBuffer));<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">byte in[] = { // plain text to encrypt };<br/></p>
<p class="paragraph_style_5">byte out[128];<br/></p>
<p class="paragraph_style_5">RNG rng;<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">InitRng(&amp;rng);<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">word32 outLen = RsaPublicEncrypt(in, sizeof(in), out, sizeof(out), &amp;rsaPublicKey, &amp;rng);<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">Now ‘<span class="style_3">out</span>’ holds the cipher text from the plain text ‘<span class="style_3">in</span>’. <span class="style_3">RsaPublicEncrypt</span>() will return the length in bytes written to out or a negative number in case of an error. <span class="style_3">RsaPublicEncrypt</span>() needs a RNG (Random Number Generator) for the padding used by the encryptor and it must be initialized before it can be used. To make sure that the output buffer is large enough to pass you can first call <span class="style_3">RsaEncryptSize</span>() which will return the number of bytes that a successful call to <span class="style_3">RsaPublicEnrypt</span>() will write. <br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4">In the event of an error, a negative return from <span class="style_3">RsaPublicEnrypt</span>(), or <span class="style_3">RsaPublicKeyDecode</span>() for that matter, you can call <span class="style_3">wolfCryptErrorString</span>() to get a string describing the error that occurred. <br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_5">void CTaoCryptErrorString(int error, char* buffer);<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">Make sure that buffer is at least <span class="style_3">MAX_ERROR_SZ</span> bytes (80).<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4">Now to decrypt out:<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_5">RsaKey rsaPrivateKey;<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">byte privateKeyBuffer[] = { // hold the raw data from the key, maybe from a file <br/></p>
<p class="paragraph_style_5">                               like RsaPrivateKey.der };<br/></p>
<p class="paragraph_style_5">word32 idx = 0;             //  where to start reading into the buffer<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">RsaPrivateKeyDecode(privateKeyBuffer, &amp;idx, &amp;rsaPrivateKey, sizeof(privateKeyBuffer));<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">byte plain[128];<br/></p>
<p class="paragraph_style_5"> <br/></p>
<p class="paragraph_style_5">word32 plainSz = RsaPrivateDecrypt(out, outLen, plain, sizeof(plain), &amp;rsaPrivateKey);<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">Now <span class="style_3">plain</span> will hold <span class="style_3">plainSz</span> bytes or an error code. For complete examples of each type in wolfCrypt please see the file wolfcrypt/test/test.c.  Note that the RsaPrivateKeyDecode function only accepts keys in raw <span class="style_3">DER</span> format.<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_6">10.5.2 DH (Diffie-Hellman)<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4">wolfCrypt provides support for Diffie-Hellman through the header &quot;<span class="style_2">wolfssl/ctaocrypt/dh.h</span>&quot;.  The Diffie-Hellman key exchange algorithm allows two parties to establish a shared secret key.  Usage is usually similar to the following example, where <span class="style_3">sideA</span> and <span class="style_3">sideB</span> designate the two parties.<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">In the following example, <span class="style_3">dhPublicKey</span> contains the Diffie-Hellman public parameters.  <span class="style_3">privA</span> holds the generated private key for sideA, <span class="style_3">pubA</span> holds the generated public key for sideA, and <span class="style_3">agreeA</span> holds the mutual key that both sides have agreed on.<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_5">DhKey     dhPublicKey;<br/></p>
<p class="paragraph_style_5">word32    idx = 0;  // where to start reading into the publicKeyBuffer<br/></p>
<p class="paragraph_style_5">word32    pubASz, pubBSz, agreeASz;<br/></p>
<p class="paragraph_style_5">byte tmp[1024];<br/></p>
<p class="paragraph_style_5">RNG  rng;<br/></p>
<p class="paragraph_style_5"><br/></p>
<p class="paragraph_style_5">byte privA[128];<br/></p>
<p class="paragraph_style_5">byte pubA[128];<br/></p>
<p class="paragraph_style_5">byte agreeA[128];<br/></p>
<p class="paragraph_style_5"><br/></p>
<p class="paragraph_style_5">InitDhKey(&amp;dhPublicKey);<br/></p>
<p class="paragraph_style_5"><br/></p>
<p class="paragraph_style_5">byte publicKeyBuffer[] = { // holds the raw data from the public key parameters, maybe from a file like dh1024.der }<br/></p>
<p class="paragraph_style_5"><br/></p>
<p class="paragraph_style_5">DhKeyDecode(tmp, &amp;idx, &amp;dhPublicKey, publicKeyBuffer);<br/></p>
<p class="paragraph_style_5"><br/></p>
<p class="paragraph_style_5">InitRng(&amp;rng);  // Initialize random number generator<br/></p>
<p class="paragraph_style_5"><br/></p>
<p class="paragraph_style_4"><span class="style_3">DhGenerateKeyPair</span>() will generate a public and private DH key based on the initial public parameters in dhPublicKey.<br/></p>
<p class="paragraph_style_5"><br/></p>
<p class="paragraph_style_5">DhGenerateKeyPair(&amp;dhPublicKey, &amp;rng, privA, &amp;privASz, pubA, &amp;pubASz);<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">After sideB sends their public key (<span class="style_3">pubB</span>) to sideA, sideA can then generate the mutually-agreed key(<span class="style_3">agreeA</span>) using the <span class="style_3">DhAgree</span>() function. <br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_5">DhAgree(&amp;dhPublicKey, agreeA, &amp;agreeASz, privA, privASz, pubB, pubBSz);<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">Now, <span class="style_3">agreeA</span> holds sideA’s mutually-generated key (of size <span class="style_3">agreeASz</span> bytes).  The same process will have been done on sideB.<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">For a complete example of Diffie-Hellman in wolfCrypt, see the file wolfcrypt/test/test.c.<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_6">10.5.3 EDH (Ephemeral Diffie-Hellman)<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4"> A wolfSSL server can do Ephemeral Diffie-Hellman.  No build changes are needed to add this feature, though an application will have to register the ephemeral group parameters on the server side to enable the EDH cipher suites.  A new API can be used to do this:<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_5">int wolfSSL_SetTmpDH(CYASSL* ssl, unsigned char* p,int pSz,unsigned char* g,int gSz);<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">The example server and echoserver use this function from <span class="style_3">SetDH</span>().<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_6">10.5.4 DSA (Digital Signature Algorithm)<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_4">wolfCrypt provides support for DSA and DSS through the header &quot;<span class="style_2">wolfssl/ctaocrypt/dsa.h</span>&quot;.  DSA allows for the creation of a digital signature based on a given data hash.  DSA uses the SHA hash algorithm to generate a hash of a block of data, then signs that hash using the signer’s private key.  Standard usage is similar to the following.  <br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">We first declare our DSA key structure (<span class="style_3">key</span>), initialize our initial message (<span class="style_3">message</span>) to be signed, and initialize our DSA key buffer (<span class="style_3">dsaKeyBuffer</span>).<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_5">DsaKey key;<br/></p>
<p class="paragraph_style_5">byte   message[] = { // message data to sign }<br/></p>
<p class="paragraph_style_5">byte   dsaKeyBuffer[] = { // holds the raw data from the DSA key, maybe from a file <br/></p>
<p class="paragraph_style_5">                           like dsa512.der }<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">We then declare our SHA structure (<span class="style_3">sha</span>), random number generator (<span class="style_3">rng</span>), array to store our SHA hash (<span class="style_3">hash</span>), array to store our signature (<span class="style_3">signature</span>), <span class="style_3">idx</span> (to mark where to start reading in our dsaKeyBuffer), and an int (<span class="style_3">answer</span>) to hold our return value after verification.<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_5">Sha  sha;<br/></p>
<p class="paragraph_style_5">RNG  rng;<br/></p>
<p class="paragraph_style_5">byte  hash[SHA_DIGEST_SIZE];<br/></p>
<p class="paragraph_style_5">byte  signature[40];<br/></p>
<p class="paragraph_style_5">word32 idx = 0;<br/></p>
<p class="paragraph_style_5">int  answer;<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">Set up and create the SHA hash.  For more information on wolfCrypt’s SHA algorithm, see section 10.1.3. The SHA hash of “<span class="style_3">message</span>” is stored in the variable “<span class="style_3">hash</span>”.<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_5">InitSha(&amp;sha);<br/></p>
<p class="paragraph_style_5">ShaUpdate(&amp;sha, message, sizeof(message));<br/></p>
<p class="paragraph_style_5">ShaFinal(&amp;sha, hash);<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">Initialize the DSA key structure, populate the structure key value, and initialize the random number generator (<span class="style_3">rng</span>).<br/></p>
<p class="paragraph_style_4"> <br/></p>
<p class="paragraph_style_5">InitDsaKey(&amp;key);<br/></p>
<p class="paragraph_style_5">DsaPrivateKeyDecode(dsaKeyBuffer, &amp;idx, &amp;key, sizeof(dsaKeyBuffer));<br/></p>
<p class="paragraph_style_5"><br/></p>
<p class="paragraph_style_5">InitRng(&amp;rng);<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">The <span class="style_3">DsaSign</span>() function creates a signature (<span class="style_3">signature</span>) using the DSA private key, hash value, and random number generator.<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_5">DsaSign(hash, signature, &amp;key, &amp;rng);<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_4">To verify the signature, use <span class="style_3">DsaVerify</span>(). If verification is successful, answer will be equal to “1”. Once finished, free the DSA key structure using <span class="style_3">FreeDsaKey</span>().<br/></p>
<p class="paragraph_style_4"><br/></p>
<p class="paragraph_style_5">DsaVerify(hash, signature, &amp;key, &amp;answer);<br/></p>
<p style="padding-bottom: 0pt; " class="paragraph_style_5">FreeDsaKey(&amp;key);</p>
</div>
</div>
</div>
<div id="id3" style="height: 24px; left: 193px; position: absolute; top: 122px; width: 268px; z-index: 1; " class="style_SkipStroke shape-with-text">
<div class="text-content graphic_textbox_layout_style_default_External_268_24" style="padding: 0px; ">
<div class="graphic_textbox_layout_style_default">
<p style="padding-bottom: 0pt; padding-top: 0pt; " class="paragraph_style_8"><a class="class1" title="Docs.html" href="Docs.html">Docs</a> <span class="style_6">-&gt;</span> <span class="style_7">wolfSSL Manual</span></p>
</div>
</div>
</div>
<div style="height: 1px; width: 698px;  height: 1px; left: 37px; position: absolute; top: 220px; width: 698px; z-index: 1; " class="tinyText">
<div style="position: relative; width: 698px; ">
<img src="Docs-wolfssl-manual-10-wolfcrypt-usage-reference_files/shapeimage_1.jpg" alt="" style="height: 1px; left: 0px; position: absolute; top: 0px; width: 698px; "/>
</div>
</div>
<div style="height: 37px; width: 545px;  height: 37px; left: 191px; position: absolute; top: 80px; width: 545px; z-index: 1; " class="tinyText">
<div style="position: relative; width: 545px; ">
<img src="Docs-wolfssl-manual-10-wolfcrypt-usage-reference_files/shapeimage_2.png" alt="" style="height: 37px; left: 0px; position: absolute; top: 0px; width: 545px; "/>
</div>
</div>
<div id="id4" style="height: 25px; left: 200px; position: absolute; top: 84px; width: 43px; z-index: 1; " class="style_SkipStroke_1 shape-with-text">
<div class="text-content graphic_textbox_layout_style_default_External_43_25" style="padding: 0px; ">
<div class="graphic_textbox_layout_style_default">
<p style="padding-bottom: 0pt; padding-top: 0pt; " class="paragraph_style_9"><a class="class2" title="Home.html" href="Home.html">Home</a></p>
</div>
</div>
</div>
<div id="id5" style="height: 25px; left: 365px; position: absolute; top: 84px; width: 72px; z-index: 1; " class="style_SkipStroke shape-with-text">
<div class="text-content graphic_textbox_layout_style_default_External_72_25" style="padding: 0px; ">
<div class="graphic_textbox_layout_style_default">
<p style="padding-bottom: 0pt; padding-top: 0pt; " class="paragraph_style_10"><a class="class3" title="https://wolfssl.com/wolfSSL/download/downloadForm.php" href="https://wolfssl.com/wolfSSL/download/downloadForm.php">Download</a></p>
</div>
</div>
</div>
<div id="id6" style="height: 25px; left: 439px; position: absolute; top: 84px; width: 59px; z-index: 1; " class="style_SkipStroke shape-with-text">
<div class="text-content graphic_textbox_layout_style_default_External_59_25" style="padding: 0px; ">
<div class="graphic_textbox_layout_style_default">
<p style="padding-bottom: 0pt; padding-top: 0pt; " class="paragraph_style_10"><a class="class4" title="License.html" href="License.html">License</a></p>
</div>
</div>
</div>
<div id="id7" style="height: 25px; left: 499px; position: absolute; top: 84px; width: 44px; z-index: 1; " class="style_SkipStroke shape-with-text">
<div class="text-content graphic_textbox_layout_style_default_External_44_25" style="padding: 0px; ">
<div class="graphic_textbox_layout_style_default">
<p style="padding-bottom: 0pt; padding-top: 0pt; " class="paragraph_style_10"><a class="class5" title="Blog/Blog.html" href="Blog/Blog.html">Blog</a></p>
</div>
</div>
</div>
<div id="id8" style="height: 25px; left: 589px; position: absolute; top: 84px; width: 80px; z-index: 1; " class="style_SkipStroke shape-with-text">
<div class="text-content graphic_textbox_layout_style_default_External_80_25" style="padding: 0px; ">
<div class="graphic_textbox_layout_style_default">
<p style="padding-bottom: 0pt; padding-top: 0pt; " class="paragraph_style_10"><a class="class6" title="Community.html" href="Community.html">Community</a></p>
</div>
</div>
</div>
<div style="height: 36px; width: 1px;  height: 36px; left: 245px; position: absolute; top: 81px; width: 0px; z-index: 1; " class="tinyText">
<div style="position: relative; width: 0px; ">
<img src="Docs-wolfssl-manual-10-wolfcrypt-usage-reference_files/shapeimage_3.png" alt="" style="height: 36px; left: 0px; position: absolute; top: 0px; width: 1px; "/>
</div>
</div>
<div style="height: 37px; width: 1px;  height: 37px; left: 296px; position: absolute; top: 80px; width: 0px; z-index: 1; " class="tinyText">
<div style="position: relative; width: 0px; ">
<img src="Docs-wolfssl-manual-10-wolfcrypt-usage-reference_files/shapeimage_4.png" alt="" style="height: 37px; left: 0px; position: absolute; top: 0px; width: 1px; "/>
</div>
</div>
<div style="height: 36px; width: 1px;  height: 36px; left: 363px; position: absolute; top: 81px; width: 0px; z-index: 1; " class="tinyText">
<div style="position: relative; width: 0px; ">
<img src="Docs-wolfssl-manual-10-wolfcrypt-usage-reference_files/shapeimage_5.png" alt="" style="height: 36px; left: 0px; position: absolute; top: 0px; width: 1px; "/>
</div>
</div>
<div style="height: 36px; width: 1px;  height: 36px; left: 438px; position: absolute; top: 81px; width: 0px; z-index: 1; " class="tinyText">
<div style="position: relative; width: 0px; ">
<img src="Docs-wolfssl-manual-10-wolfcrypt-usage-reference_files/shapeimage_6.png" alt="" style="height: 36px; left: 0px; position: absolute; top: 0px; width: 1px; "/>
</div>
</div>
<div style="height: 37px; width: 1px;  height: 37px; left: 498px; position: absolute; top: 80px; width: 0px; z-index: 1; " class="tinyText">
<div style="position: relative; width: 0px; ">
<img src="Docs-wolfssl-manual-10-wolfcrypt-usage-reference_files/shapeimage_7.png" alt="" style="height: 37px; left: 0px; position: absolute; top: 0px; width: 1px; "/>
</div>
</div>
<div style="height: 37px; width: 1px;  height: 37px; left: 589px; position: absolute; top: 80px; width: 0px; z-index: 1; " class="tinyText">
<div style="position: relative; width: 0px; ">
<img src="Docs-wolfssl-manual-10-wolfcrypt-usage-reference_files/shapeimage_8.png" alt="" style="height: 37px; left: 0px; position: absolute; top: 0px; width: 1px; "/>
</div>
</div>
<div id="id9" style="height: 25px; left: 671px; position: absolute; top: 84px; width: 61px; z-index: 1; " class="style_SkipStroke shape-with-text">
<div class="text-content graphic_textbox_layout_style_default_External_61_25" style="padding: 0px; ">
<div class="graphic_textbox_layout_style_default">
<p style="padding-bottom: 0pt; padding-top: 0pt; " class="paragraph_style_10"><a class="class7" title="Contact.html" href="Contact.html">Contact</a></p>
</div>
</div>
</div>
<div id="id10" style="height: 25px; left: 249px; position: absolute; top: 84px; width: 44px; z-index: 1; " class="style_SkipStroke shape-with-text">
<div class="text-content graphic_textbox_layout_style_default_External_44_25" style="padding: 0px; ">
<div class="graphic_textbox_layout_style_default">
<p style="padding-bottom: 0pt; padding-top: 0pt; " class="paragraph_style_9"><a class="class8" title="About.html" href="About.html">About</a></p>
</div>
</div>
</div>
<div style="height: 36px; width: 1px;  height: 36px; left: 670px; position: absolute; top: 81px; width: 0px; z-index: 1; " class="tinyText">
<div style="position: relative; width: 0px; ">
<img src="Docs-wolfssl-manual-10-wolfcrypt-usage-reference_files/shapeimage_9.png" alt="" style="height: 36px; left: 0px; position: absolute; top: 0px; width: 1px; "/>
</div>
</div>
<div id="id11" style="height: 25px; left: 298px; position: absolute; top: 84px; width: 63px; z-index: 1; " class="style_SkipStroke_1 shape-with-text">
<div class="text-content graphic_textbox_layout_style_default_External_63_25" style="padding: 0px; ">
<div class="graphic_textbox_layout_style_default">
<p style="padding-bottom: 0pt; padding-top: 0pt; " class="paragraph_style_10"><a class="class9" title="Products.html" href="Products.html">Products</a></p>
</div>
</div>
</div>
<div id="id12" style="height: 25px; left: 549px; position: absolute; top: 84px; width: 41px; z-index: 1; " class="style_SkipStroke shape-with-text">
<div class="text-content graphic_textbox_layout_style_default_External_41_25" style="padding: 0px; ">
<div class="graphic_textbox_layout_style_default">
<p style="padding-bottom: 0pt; padding-top: 0pt; " class="paragraph_style_9"><a class="class10" title="Docs.html" href="Docs.html">Docs</a></p>
</div>
</div>
</div>
<div style="height: 37px; width: 1px;  height: 37px; left: 545px; position: absolute; top: 80px; width: 0px; z-index: 1; " class="tinyText">
<div style="position: relative; width: 0px; ">
<img src="Docs-wolfssl-manual-10-wolfcrypt-usage-reference_files/shapeimage_10.png" alt="" style="height: 37px; left: 0px; position: absolute; top: 0px; width: 1px; "/>
</div>
</div>
<div id="id13" style="height: 27px; left: 634px; position: absolute; top: 224px; width: 102px; z-index: 1; " class="style_SkipStroke shape-with-text">
<div class="text-content graphic_textbox_layout_style_default_External_102_27" style="padding: 0px; ">
<div class="graphic_textbox_layout_style_default">
<p style="padding-bottom: 0pt; padding-top: 0pt; " class="paragraph_style_11"><a class="class11" title="Docs-wolfssl-manual-11-ssl-tutorial.html" href="Docs-wolfssl-manual-11-ssl-tutorial.html">Next Chapter</a></p>
</div>
</div>
</div>
<div id="id14" style="height: 25px; left: 35px; position: absolute; top: 224px; width: 125px; z-index: 1; " class="style_SkipStroke shape-with-text">
<div class="text-content graphic_textbox_layout_style_default_External_125_25" style="padding: 0px; ">
<div class="graphic_textbox_layout_style_default">
<p style="padding-bottom: 0pt; padding-top: 0pt; " class="paragraph_style_12"><a class="class12" title="Docs-wolfssl-manual-9-library-design.html" href="Docs-wolfssl-manual-9-library-design.html">Previous Chapter</a></p>
</div>
</div>
</div>
<div id="id15" style="height: 27px; left: 59px; position: absolute; top: 190px; width: 196px; z-index: 1; " class="style_SkipStroke shape-with-text">
<div class="text-content graphic_textbox_layout_style_default_External_196_27" style="padding: 0px; ">
<div class="graphic_textbox_layout_style_default">
<p style="padding-bottom: 0pt; padding-top: 0pt; " class="paragraph_style_13"><a class="class13" title="https://www.wolfssl.com/documentation/wolfSSL-Manual.pdf" href="https://www.wolfssl.com/documentation/wolfSSL-Manual.pdf">Download wolfSSL Manual (PDF)</a></p>
</div>
</div>
</div>
<div style="height: 22px; width: 22px;  height: 22px; left: 33px; position: absolute; top: 191px; width: 22px; z-index: 1; " class="tinyText style_SkipStroke_2">
<img src="Docs-wolfssl-manual-10-wolfcrypt-usage-reference_files/PDF.png" alt="" style="border: none; height: 22px; width: 22px; "/>
</div>
<div id="id16" style="height: 25px; left: 323px; position: absolute; top: 224px; width: 125px; z-index: 1; " class="style_SkipStroke shape-with-text">
<div class="text-content graphic_textbox_layout_style_default_External_125_25" style="padding: 0px; ">
<div class="graphic_textbox_layout_style_default">
<p style="padding-bottom: 0pt; padding-top: 0pt; " class="paragraph_style_14"><a title="Docs-wolfssl-manual-toc.html" href="Docs-wolfssl-manual-toc.html">Table of Contents</a></p>
</div>
</div>
</div>
<div style="height: 16px; width: 20px;  height: 16px; left: 706px; position: absolute; top: 51px; width: 20px; z-index: 1; " class="tinyText">
<div style="position: relative; width: 20px; ">
<img src="Docs-wolfssl-manual-10-wolfcrypt-usage-reference_files/shapeimage_11.png" alt="" style="height: 16px; left: 0px; position: absolute; top: 0px; width: 20px; "/>
</div>
</div>
<div style="height: 19px; width: 19px;  height: 19px; left: 707px; position: absolute; top: 25px; width: 19px; z-index: 1; " class="tinyText style_SkipStroke_2">
<img src="Docs-wolfssl-manual-10-wolfcrypt-usage-reference_files/United%20Kingdom(Great%20Britain).png" alt="" style="border: none; height: 19px; width: 19px; "/>
</div>
<div id="id17" style="height: 23px; left: 328px; position: absolute; top: 48px; width: 258px; z-index: 1; " class="style_SkipStroke shape-with-text">
<div class="text-content graphic_textbox_layout_style_default_External_258_23" style="padding: 0px; ">
<div class="graphic_textbox_layout_style_default">
<p style="padding-bottom: 0pt; padding-top: 0pt; " class="paragraph_style_15">Questions? +1 (425) 245-8247</p>
</div>
</div>
</div>
<div style="height: 19px; width: 19px;  height: 19px; left: 685px; position: absolute; top: 25px; width: 19px; z-index: 1; " class="tinyText style_SkipStroke_2">
<a href="http://www.wolfssl.jp/" title="http://www.wolfssl.jp"><img src="Docs-wolfssl-manual-10-wolfcrypt-usage-reference_files/japan.png" alt="" style="border: none; height: 19px; width: 19px; "/></a>
</div>
<div id="id18" style="height: 28px; left: 593px; position: absolute; top: 44px; width: 119px; z-index: 1; " class="style_SkipStroke shape-with-text">
<div class="text-content graphic_textbox_layout_style_default_External_119_28" style="padding: 0px; ">
<div class="graphic_textbox_layout_style_default">
<p style="padding-bottom: 0pt; padding-top: 0pt; " class="paragraph_style_16"><a class="class14" title="https://www.wolfssl.com/forums" href="https://www.wolfssl.com/forums">Support <span class="style_8">Forums</span></a></p>
</div>
</div>
</div>
<div style="height: 121px; width: 155px;  height: 121px; left: 32px; position: absolute; top: 5px; width: 155px; z-index: 1; " class="tinyText style_SkipStroke_2">
<a href="Home.html" title="Home.html"><img src="Docs-wolfssl-manual-10-wolfcrypt-usage-reference_files/wolfssl_logo.png" alt="" style="border: none; height: 121px; width: 156px; "/></a>
</div>
<div style="height: 8680px; line-height: 8680px; " class="spacer"> </div>
</div>
<div style="height: 100px; margin-left: 0px; position: relative; width: 770px; z-index: 15; " id="footer_layer">
<div style="height: 0px; line-height: 0px; " class="bumper"> </div>
<div id="id19" style="height: 27px; left: 634px; position: absolute; top: 27px; width: 102px; z-index: 1; " class="style_SkipStroke shape-with-text">
<div class="text-content graphic_textbox_layout_style_default_External_102_27" style="padding: 0px; ">
<div class="graphic_textbox_layout_style_default">
<p style="padding-bottom: 0pt; padding-top: 0pt; " class="paragraph_style_11"><a class="class15" title="Docs-wolfssl-manual-11-ssl-tutorial.html" href="Docs-wolfssl-manual-11-ssl-tutorial.html">Next Chapter</a></p>
</div>
</div>
</div>
<div id="id20" style="height: 25px; left: 35px; position: absolute; top: 27px; width: 125px; z-index: 1; " class="style_SkipStroke shape-with-text">
<div class="text-content graphic_textbox_layout_style_default_External_125_25" style="padding: 0px; ">
<div class="graphic_textbox_layout_style_default">
<p style="padding-bottom: 0pt; padding-top: 0pt; " class="paragraph_style_17"><a class="class16" title="Docs-wolfssl-manual-9-library-design.html" href="Docs-wolfssl-manual-9-library-design.html">Previous Chapter</a></p>
</div>
</div>
</div>
<div id="id21" style="height: 25px; left: 323px; position: absolute; top: 27px; width: 125px; z-index: 1; " class="style_SkipStroke shape-with-text">
<div class="text-content graphic_textbox_layout_style_default_External_125_25" style="padding: 0px; ">
<div class="graphic_textbox_layout_style_default">
<p style="padding-bottom: 0pt; padding-top: 0pt; " class="paragraph_style_14"><a class="class17" title="Docs-wolfssl-manual-toc.html" href="Docs-wolfssl-manual-toc.html">Table of Contents</a></p>
</div>
</div>
</div>
<div id="id22" style="height: 29px; left: 35px; position: absolute; top: 65px; width: 701px; z-index: 1; " class="style_SkipStroke shape-with-text">
<div class="text-content graphic_textbox_layout_style_default_External_701_29" style="padding: 0px; ">
<div class="graphic_textbox_layout_style_default">
<p style="padding-bottom: 0pt; padding-top: 0pt; " class="paragraph_style_18">Copyright 2017 wolfSSL Inc.  All rights reserved.</p>
</div>
</div>
</div>
</div>
</div>
</div>
 </body>

<!-- Mirrored from www.wolfssl.com/wolfSSL/Docs-wolfssl-manual-10-wolfcrypt-usage-reference.html by HTTrack Website Copier/3.x [XR&CO'2014], Tue, 17 Jan 2017 13:29:25 GMT -->
</html>
